////////////////////////////////////////////////////////////////////////////////
//
//  Copyright (C) 2003-2006 Adobe Macromedia Software LLC and its licensors.
//  All Rights Reserved. The following is Source Code and is subject to all
//  restrictions on such code as contained in the End User License Agreement
//  accompanying this product.
//
////////////////////////////////////////////////////////////////////////////////

package mx.charts.chartClasses
{

import flash.events.IEventDispatcher;
import mx.charts.AxisLabel;

/**
 *  The IAxis class is an abstract interface for defining label,
 *  tick mark, and data positioning properties for a chart axis.
 *
 *  <p>Classes implement this interface to provide
 *  range definition functionality.</p>
 *
 *  @see mx.charts.CategoryAxis
 *  @see mx.charts.LinearAxis
 */
public interface IAxis extends IEventDispatcher
{
	//--------------------------------------------------------------------------
	//
	//  Properties
	//
	//--------------------------------------------------------------------------

	//----------------------------------
	//  baseline
	//----------------------------------

	/**
	 *  The baseline position for the axis.
	 *  Some series, such as ColumnSeries or AreaSeries, use this value to
	 *  define the base of a filled region when no minimum value is specified.
	 */
	function get baseline():Number;
	
	//----------------------------------
	//  chartDataProvider
	//----------------------------------

	/**
	 *  The data provider assigned to the enclosing chart.
	 *  Axis types that are data provider-based can choose to inherit
	 *  the data provider associated with the enclosing chart.
	 *  If an axis is shared among multiple charts,
	 *  the value of this property is <code>undefined</code>
	 *  (most likely it will be the last data provider assigned
	 *  to one of the associated charts).
	 */
	function set chartDataProvider(value:Object):void;
	
	//----------------------------------
	//  name
	//----------------------------------

	/** 
	 *  The name of the axis.
	 *  If set, Flex uses this name to format DataTip controls.
	 */
	function get displayName():String;

	//----------------------------------
	//  title
	//----------------------------------

	/**
	 *  The text for the title displayed along the axis.  
	 */
	function get title():String;

	//----------------------------------
	//  unitSize
	//----------------------------------

	/**
	 *  The size of one unit of data as represented by this axis.
	 *  This value is used by various series types to help in rendering.
	 *  The ColumnSeries class, for example, uses this value
	 *  to determine how wide columns should be rendered.
	 *  Different axis types return different values,
	 *  sometimes dependent on the data being represented.
	 *  The DateTimeAxis class, for example, might return the number
	 *  of milliseconds in a day, or a year, depending on the data
	 *  that is rendered in the chart.
	 *  Because this value is dependant on collecting the represented data,
	 *  custom series cannot assume this value is accurate in their
	 *  <code>updateData()</code> or <code>updateMapping()</code> methods. 
	 */
	function get unitSize():Number
	
	//--------------------------------------------------------------------------
	//
	//  Methods: Data conversion
	//
	//--------------------------------------------------------------------------

	/**
	 *  Converts a set of values of arbitrary type
	 *  to a set of numbers that can be transformed into screen coordinates.
	 *
	 *  @param cache An Array of objects where converted values
	 *  are read from and stored.
	 *
	 *  @param field The field of the objects in the cache Array
	 *  containing the pre-converted values.
	 *
	 *  @param convertedField The field of the objects in the cache Array
	 *  where converted values should be stored.
	 *
	 *  @param indexValues This parameter is <code>true</code> if the values being mapped
	 *  are index values, and <code>false</code> if they are natural data values.
	 */
	function mapCache(cache:Array, field:String, convertedField:String,
					  indexValues:Boolean = false):void
	
	/**
	 *  Filters a set of values of arbitrary type
	 *  to a set of numbers that can be mapped.
	 *
	 *  @param cache An Array of objects where converted values
	 *  are read from and stored.
	 *
	 *  @param field The field of the objects in the cache Array
	 *  containing the pre-filtered values.
	 *
	 *  @param convertedField The field of the objects in the cache Array
	 *  where filtered values should be stored.
	 */
	function filterCache(cache:Array, field:String,
						 filteredString:String):void;
	
	/**
	 *  Maps a set of values from data space to screen space.
	 *
	 *  @param cache An Array of objects where mapped values
	 *  are read from and stored.
	 *
	 *  @param field The field of the objects in the cache Array
	 *  containing the pre-mapped values.
	 *
	 *  @param convertedField The field of the objects in the cache Array
	 *  where mapped values should be stored.
	 */
	function transformCache(cache:Array, field:String,
							convertedField:String):void;

	//--------------------------------------------------------------------------
	//
	//  Methods: Data inversion
	//
	//--------------------------------------------------------------------------

	/**
	 *  Maps a position along the axis back to a numeric data value.
	 *
	 *  @param value The bound of the axis.
	 *  This parameter should be between 0 and 1,
	 *  with 0 representing the minimum bound of the axis, and 1 the maximum.
	 */
	function invertTransform(value:Number):Object;

	/**
	 *  Formats values for display in DataTips.
	 *  Returns a user-readable string.
	 *
	 *  @param value The value to convert to a String. 
	 *  
	 *  @return The text of the DataTip.
	 */
	function formatForScreen(value:Object):String	

	//--------------------------------------------------------------------------
	//
	//  Methods: Label management
	//
	//--------------------------------------------------------------------------
		
	/**
	 *  Determines the range to estimate what the axis labels should be. 
	 *  The axis almost immediately calls the <code>getLabels()</code> method
	 *  to get the real values.
	 *  The axis uses the estimated values to adjust chart margins,
	 *  so any difference between the estimated labels and  actual labels
	 *  (returned from the <code>getLabels()</code> method) results in scaling
	 *  the labels to fit.
	 *
	 *  <p>An axis need only return the minimum and maximum labels
	 *  when returning an estimate.
	 *  If the label set is fairly static, without depending on the size
	 *  of the axis being rendered on screen, an axis can return the entire
	 *  label set from this function, and mark the estimate as accurate.</p>
	 *  
	 *  @return An Array of AxisLabel objects.
	 */
	function getLabelEstimate():AxisLabelSet;

	/** 
	 *  Determines how the axis handles overlapping labels. 
	 *  Typically, numeric ranges return <code>true</code>,
	 *  while discrete value-based ranges do not.
	 *  You can can override this property by setting it directly on the axis.
	 *
	 *  @return <code>true</code> if labels can be dropped without loss of data;
	 *  otherwise, <code>false</code>. 
	 */
	function preferDropLabels():Boolean;
	
	/**
	 *  Gets the labels text that is rendered.
	 *  When Flex calls this method, 
	 *  the axis has already determined the minimum length of the label.
	 *  
	 *  @param minimumAxisLength The minimum length of the axis, in pixels.
	 *  The axis can be longer than this value, but not shorter.
	 *  
	 *  @return An array of AxisLabel objects.
	 */
	function getLabels(minimumAxisLength:Number):AxisLabelSet;

	/**
	 *  Invoked when an AxisRenderer is unable to cleanly render
	 *  the labels without overlap, and would like the Axis object
	 *  to reduce the set of labels.
	 *  The method is passed the two labels that are overlapping.
	 *
	 *  @param intervalStart The start of the interval where labels overlap.
	 *
	 *  @param intervalEnd The end of the interval where labels overlap.
	 *
	 *  @return A new label set that resolves the overlap by reducing
	 *  the number of labels.
	 */
	function reduceLabels(intervalStart:AxisLabel,
						  intervalEnd:AxisLabel):AxisLabelSet;

	//--------------------------------------------------------------------------
	//
	//  Methods: Notification
	//
	//--------------------------------------------------------------------------

	/**
	 *  Each DataTransform that makes use of an axis
	 *  registers itself with that axis.
	 *  The axis is responsible for informing the transform
	 *  when its relevant values have changed.
	 *  It should also request values from the transform
	 *  when it wants to autogenerate minimum and maximum values.
	 *
	 *  @param transform The DataTransform to register.
	 *
	 *  @param dimensionName The name of the dimension.
	 */
	function registerDataTransform(transform:DataTransform,
								   dimensionName:String):void;
	
	/**
	 *  Each DataTransform that makes use of an axis
	 *  registers itself with that axis.
	 *  The axis is responsible for informing the transform
	 *  when its relevant values have changed.
	 *  It should also request values from the transform
	 *  when it wants to autogenerate minimum and maximum values.
	 *
	 *  @param transform The DataTransform to unregister.
	 */
	function unregisterDataTransform(transform:DataTransform):void;

	/** 
	 *  Triggers events that inform the range object
	 *  when the chart data has changed.
	 */
	function dataChanged():void;

	/**
	 *  Updates the chart.
	 *  This can be called multiple times per frame. 
	 */
	function update():void;
}

}
